Skip to content

feat(extensions): add OperationValidator.precheck pre-body-parse hook#1548

Open
cdbartholomew wants to merge 1 commit into
mainfrom
fix/credit-check-before-body-parse
Open

feat(extensions): add OperationValidator.precheck pre-body-parse hook#1548
cdbartholomew wants to merge 1 commit into
mainfrom
fix/credit-check-before-body-parse

Conversation

@cdbartholomew
Copy link
Copy Markdown
Contributor

Summary

  • Adds an optional precheck() method to OperationValidator that lets an extension gate a request before its body is read.
  • Wired as a FastAPI Depends ahead of the body parameter on the billable POST routes (retain, recall, reflect, files retain, mental-model create + refresh).
  • Default is a no-op accept; existing validators are unaffected. Useful when an extension wants to short-circuit a request that would otherwise allocate a large body just to be rejected post-parse (e.g., quota exhausted).

Test plan

  • +7 unit tests in tests/test_extensions.py covering: default no-op accept, rejection short-circuits before body parse (asserted via Pydantic model_validator(mode='before') recorder — body never deserialized on reject), rejection returns the validator's status code + reason, GET routes are unaffected, accept lets request through to body parse, body-parse-skipped behaviour holds for retain/recall/reflect.
  • All 7 new tests + 8 pre-existing non-DB tests pass locally (uv run pytest tests/test_extensions.py → 15 passed). The 21 errors visible in the same run are pre-existing environment issues (missing LLM API key, alembic state) on main itself — verified independent of this PR.

Add an optional ``precheck`` method to ``OperationValidatorExtension`` that
extensions can override to gate a request *before* its body is read off the
wire. Wire it as a FastAPI ``Depends`` ahead of the body parameter on the
billable POST routes (retain, recall, reflect, file retain, mental-model
create, mental-model refresh) so a rejecting precheck short-circuits the
request without ever materialising the JSON payload in memory.

The post-body-parse ``validate_retain`` / ``validate_recall`` /
``validate_reflect`` hooks are unchanged and remain the source of truth for
precise per-call cost and quota arithmetic. ``precheck`` is intentionally a
cheap, side-effect-free check — its sole purpose is to let an extension
short-circuit work that would otherwise allocate the request body
unnecessarily (e.g. a quota-exhausted caller submitting many large bodies).

Why before body parse:

FastAPI resolves dependencies before deserialising the route's body
parameter. A validator that runs only after parse — i.e. inside the route
handler's body — sees the already-materialised request, which is the wrong
layer for "this caller should not be allowed to spend resources on this
request at all" decisions. Wiring as ``Depends`` puts the gate at the right
layer with a one-line change per route.

Verified:

- FastAPI 0.125.0 resolves ``Depends`` raising ``HTTPException`` before
  Pydantic deserialises the body, regardless of declaration order. A
  reproducer using a ``model_validator(mode='before')`` recorder confirms
  zero body-parse calls on the rejection path.
- The new ``PrecheckContext`` carries only operation name + bank_id +
  request_context (already-resolved tenant). No body access — by design.
- Default ``precheck`` returns ``ValidationResult.accept()``; existing
  validators are unaffected.

Tests: +7 unit tests covering the default no-op, the FastAPI Depends
wiring, accept/reject paths, status-code/reason propagation, and explicit
"body never parsed on rejection" assertions for retain / recall / reflect
plus a "GET routes are unaffected" guard. All passing.
@cdbartholomew cdbartholomew requested a review from nicoloboschi May 8, 2026 18:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant